---
title: 打印
icon: '#pro/Printer'
---

<MetaData
  lang="zh-CN"
  isPro
  meta={{
    preset: [{
      client: '@univerjs/preset-sheets-advanced',
      locale: '@univerjs/preset-sheets-advanced/locales/zh-CN',
      style: '@univerjs/preset-sheets-advanced/lib/index.css',
    }],
    plugins: [{
      client: '@univerjs-pro/sheets-print',
      facade: '@univerjs-pro/sheets-print/facade',
      locale: '@univerjs-pro/sheets-print/locale/zh-CN',
      style: '@univerjs-pro/sheets-print/lib/index.css',
    }],
    server: '否',
  }}
/>

打印功能允许用户将表格内容打印为纸质文档或导出为 PDF 格式，便于离线查看和分享。

<PlaygroundFrame lang="zh-CN" slug="sheets/print" clickToShow />

## 预设模式

打印功能被包含在 `@univerjs/preset-sheets-advanced` 预设中。

### 安装

<Callout>
  @univerjs/preset-sheets-advanced 的 `UniverSheetsAdvancedPreset` 预设在运行时依赖 `UniverSheetsDrawingPreset` 预设，请先安装 @univerjs/preset-sheets-drawing。
</Callout>

```package-install
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

### 使用

```typescript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced' // [!code ++]
import UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingZhCN from '@univerjs/preset-sheets-drawing/locales/zh-CN' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-sheets-advanced/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      UniverPresetSheetsCoreZhCN,
      UniverPresetSheetsDrawingZhCN, // [!code ++]
      UniverPresetSheetsAdvancedZhCN, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})
```

如果你拥有 Univer 的商业许可证，请参考[在客户端使用许可证](/guides/pro/license#在预设模式中使用)进行配置。

### 预设与配置

```typescript
interface IUniverSheetsAdvancedPresetConfig {
  print?: Partial<IUniverSheetsPrintConfig>
}

interface IUniverSheetsPrintConfig {
  /**
   * 是否强制打印时显示水印
   * @default false
   */
  enforceWatermark?: boolean
}
```

## 插件模式

### 安装

```package-install
npm install @univerjs-pro/sheets-print
```

### 使用

```typescript
import { UniverSheetsPrintPlugin } from '@univerjs-pro/sheets-print' // [!code ++]
import SheetsPrintPluginZhCN from '@univerjs-pro/sheets-print/locale/zh-CN' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/sheets-print/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      SheetsPrintPluginZhCN, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsPrintPlugin) // [!code ++]
```

如果你拥有 Univer 的商业许可证，请参考[在客户端使用许可证](/guides/pro/license#在插件模式中使用)进行配置。

### 插件与配置

```typescript
interface IUniverSheetsPrintConfig {
  /**
   * 是否强制打印时显示水印
   * @default false
   */
  enforceWatermark?: boolean
}
```

## Facade API

### 打开打印配置对话框

使用 `FWorkbook.openPrintDialog` 可以打开打印配置对话框。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()

fWorkbook.openPrintDialog()
```

### 关闭打印配置对话框

使用 `FWorkbook.closePrintDialog` 方法可以关闭打印配置对话框。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.openPrintDialog()

// 3 秒后关闭打印配置对话框
setTimeout(() => {
  fWorkbook.closePrintDialog()
}, 3000)
```

### 更新打印布局配置

使用 [`FWorkbook.updatePrintConfig(config: ISheetPrintLayoutConfig)`](https://reference.univer.ai/zh-CN/classes/FWorkbook#updateprintconfig) 方法更新打印布局配置。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const subUnitId = fWorksheet.getSheetId()

// 更新打印布局配置
fWorkbook.updatePrintConfig({
  area: univerAPI.Enum.PrintArea.CurrentSheet, // 打印当前工作表
  subUnitIds: [subUnitId],
  paperSize: univerAPI.Enum.PrintPaperSize.A4, // A4 纸张大小
  scale: univerAPI.Enum.PrintScale.FitPage, // 使内容适应页面
  freeze: [univerAPI.Enum.PrintFreeze.Row], // 冻结行标题
  margin: univerAPI.Enum.PrintPaperMargin.Normal, // 正常边距
  // ... 其他设置
})

// 开始打印
fWorkbook.print()
```

<details>
  <summary>以下是 `ISheetPrintLayoutConfig` 的完整定义：</summary>
  ```typescript
  /**
   * 打印布局设置的配置接口
   */
  export interface ISheetPrintLayoutConfig {
    /**
     * 指定要打印的工作表区域（例如，当前工作表，选区）
     */
    area: PrintArea
    /**
     * 要打印的工作簿的工作表 ID 集合，或者包含工作表 ID 和范围的对象集合
     */
    subUnitIds: (string | { id: string, range: IRange })[]
    /**
     * 打印纸张大小设置（例如，A4，信纸）
     */
    paperSize: PrintPaperSize
    /**
     * 打印页面方向（纵向或横向）
     */
    direction: PrintDirection
    /**
     * 打印缩放类型
     */
    scale: PrintScale
    /**
     * 自定义缩放百分比
     */
    customScale: number
    /**
     * 冻结行和列的设置数组
     */
    freeze: PrintFreeze[]
    /**
     * 打印页面的边距预设
     */
    margin: PrintPaperMargin
    /**
     * 使用自定义纸张尺寸时的自定义页面尺寸
     */
    pageSizeCustom?: { w: number, h: number }
    /**
     * 每页打印的最大行数
     */
    maxRowsEachPage: number
    /**
     * 每页打印的最大列数
     */
    maxColumnsEachPage: number
  }

  /**
   * 定义要打印的电子表格区域
   */
  export enum PrintArea {
    /** 只打印当前活动工作表 */
    CurrentSheet = 'CurrentSheet',
    /** 打印整个工作簿 */
    workbook = 'Workbook',
    /** 只打印当前选定的范围 */
    CurrentSelection = 'CurrentSelection',
    /** 打印所有选定的范围 */
    AllSelection = 'AllSelection',
  }

  /**
   * 定义打印纸张大小
   */
  export enum PrintPaperSize {
    /** 使用信纸大小 */
    Letter = 'Letter',
    /** 使用小报纸大小 */
    Tabloid = 'Tabloid',
    /** 使用法律纸张大小 */
    Legal = 'Legal',
    /** 使用报表纸张大小 */
    Statement = 'Statement',
    /** 使用行政公文纸张大小 */
    Executive = 'Executive',
    /** 使用对折纸张大小 */
    Folio = 'Folio',
    /** 使用A3纸张大小 */
    A3 = 'A3',
    /** 使用A4纸张大小 */
    A4 = 'A4',
    /** 使用A5纸张大小 */
    A5 = 'A5',
    /** 使用B4纸张大小 */
    B4 = 'B4',
    /** 使用B5纸张大小 */
    B5 = 'B5',
  }

  /**
   * 定义打印页面的方向
   */
  export enum PrintDirection {
    /** 纵向方向 */
    Portrait = 'Portrait',
    /** 横向方向 */
    Landscape = 'Landscape',
  }

  /**
   * 定义打印的缩放类型
   */
  export enum PrintScale {
    /** 正常缩放 */
    Origin = 'Origin',
    /** 适合宽度 */
    FitWidth = 'FitWidth',
    /** 适合高度 */
    FitHeight = 'FitHeight',
    /** 适合页面大小 */
    FitPage = 'FitPage',
    /** 自定义缩放 */
    Custom = 'Custom',
  }

  /**
   * 定义打印时应保持冻结的元素
   */
  export enum PrintFreeze {
    /** 打印时保持行标题冻结 */
    Row = 'Row',
    /** 打印时保持列标题冻结 */
    Column = 'Column',
  }

  /**
   * 定义打印页面的边距预设
   */
  export enum PrintPaperMargin {
    /** 使用正常边距 */
    Normal = 'Normal',
    /** 使用窄边距 */
    Narrow = 'Narrow',
    /** 使用宽边距 */
    Wide = 'Wide',
    /** 没有边距 */
    None = 'None',
  }
  ```
</details>

### 更新打印渲染配置

使用 [`FWorkbook.updatePrintRenderConfig(config: ISheetPrintRenderConfig)`](https://reference.univer.ai/zh-CN/classes/FWorkbook#updateprintrenderconfig) 方法更新打印渲染配置。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()

// 更新默认打印布局配置
fWorkbook.updatePrintConfig({})

// 更新打印渲染配置
fWorkbook.updatePrintRenderConfig({
  gridlines: true, // 显示网格线
  hAlign: univerAPI.Enum.PrintAlign.Middle, // 水平居中对齐
  vAlign: univerAPI.Enum.PrintAlign.Middle, // 垂直居中对齐
  headerFooter: [ // 要包含的页眉和页脚元素数组，这里是页码和工作表名称
    univerAPI.Enum.PrintHeaderFooter.PageSize,
    univerAPI.Enum.PrintHeaderFooter.WorksheetTitle,
  ],
  // ... 其他设置
})

// 开始打印
fWorkbook.print()
```

<details>
  <summary>以下是 `ISheetPrintRenderConfig` 的完整定义：</summary>
  ```typescript
  /**
   * 打印渲染选项的配置接口
   */
  export interface ISheetPrintRenderConfig {
    /**
     * 是否在打印输出中显示网格线
     */
    gridlines: boolean
    /**
     * 水平对齐设置
     */
    hAlign: PrintAlign
    /**
     * 垂直对齐设置
     */
    vAlign: PrintAlign
    /**
     * 包含的页眉和页脚元素数组
     */
    headerFooter: PrintHeaderFooter[]
    /**
     * 页眉和页脚的详细设置
     */
    headerFooterSetting: IPrintHeaderFooter
    /**
     * 是否使用自定义页眉和页脚而不是预设
     */
    isCustomHeaderFooter?: boolean

    watermark?: Nullable<IWatermarkConfigWithType>
  }

  /**
   * 定义打印内容的可用对齐选项
   */
  export enum PrintAlign {
    /** 水平方向左对齐，垂直方向顶部对齐 */
    Start = 'Start',
    /** 水平方向右对齐，垂直方向底部对齐 */
    End = 'End',
    /** 水平方向居中对齐，垂直方向居中对齐 */
    Middle = 'Middle',
  }

  /**
   * 定义页眉和页脚内容的可用占位符
   */
  export enum PrintHeaderFooter {
    /** 插入当前页码信息 */
    PageSize = 'PageSize',
    /** 插入工作簿名称 */
    WorkbookTitle = 'WorkbookTitle',
    /** 插入工作表名称 */
    WorksheetTitle = 'WorksheetTitle',
    /** 插入当前日期 */
    Date = 'Date',
    /** 插入当前时间 */
    Time = 'Time',
  }

  /**
   * 页眉和页脚内容定位的配置接口
   */
  export interface IPrintHeaderFooter {
    /** 左上角显示的内容 */
    topLeft: string
    /** 顶部中心显示的内容 */
    topCenter: string
    /** 右上角显示的内容 */
    topRight: string
    /** 左下角显示的内容 */
    bottomLeft: string
    /** 底部中心显示的内容 */
    bottomCenter: string
    /** 右下角显示的内容 */
    bottomRight: string
  }
  ```
</details>

### 调起打印

使用 `FWorkbook.print` 方法可以直接调起打印。

```typescript
// 使用默认配置可以传入空对象
workbook.updatePrintConfig({
  // ... 打印布局配置
})
workbook.updatePrintRenderConfig({
  // ... 打印渲染配置
})
workbook.print()
```

### 保存截图至剪贴板

使用 `FWorkbook.saveScreenshotToClipboard` 方法可以保存打印数据图片到剪切板。

该 API 仅在拥有 [许可证](zh-CN/guides/pro/license) 的情况下可用，未持有许可证时将受到使用限制，保存操作将返回 `false`。

我们使用 Clipboard API 保存图片到剪贴板，在非安全网络环境或某些不支持的浏览器可能会保存失败。保存成功会返回 `true`。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const result = await fWorkbook.saveScreenshotToClipboard()
```

### 获取选区截图

使用 `FRange.getScreenshot` 方法可以获取选区打印数据图片。

该 API 仅在持有 [许可证](zh-CN/guides/pro/license) 时可用，未持证用户将受到使用限制，保存失败时返回 `false`，成功时返回图片的 base64 字符串。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:D10')
fRange.getScreenshot()
```

### 事件监听

完整事件类型定义，请查看 [Events](https://reference.univer.ai/zh-CN/classes/FEventName)。

`univerAPI.Event.BeforeSheetPrintOpen` 事件在打开打印配置对话框之前触发。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintOpen, (params) => {
  const { workbook, worksheet } = params

  // 取消打开打印配置对话框操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`
```

`univerAPI.Event.SheetPrintOpen` 事件在打开打印配置对话框之后触发。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintOpen, (params) => {
  const { workbook, worksheet } = params
})

// 移除事件监听器，使用 `disposable.dispose()`
```

`univerAPI.Event.BeforeSheetPrintConfirm` 事件在确认打印之前触发。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintConfirm, (params) => {
  const { renderConfig, layoutConfig } = params

  // 取消打印确认操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`
```

`univerAPI.Event.SheetPrintConfirmed` 事件在确认打印之后触发。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintConfirmed, (params) => {
  const { renderConfig, layoutConfig } = params
})

// 移除事件监听器，使用 `disposable.dispose()`
```

`univerAPI.Event.BeforeSheetPrintCanceled` 事件在取消打印之前触发。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintCanceled, (params) => {
  const { renderConfig, layoutConfig } = params

  // 取消打印取消操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`
```

`univerAPI.Event.SheetPrintCanceled` 事件在取消打印之后触发。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintCanceled, (params) => {
  const { renderConfig, layoutConfig } = params
})

// 移除事件监听器，使用 `disposable.dispose()`
```
